Skip to content

docs: add documentation for admin cli - #832

Merged
TechHutTV merged 1 commit into
mainfrom
docs/admin-cli
Jul 22, 2026
Merged

docs: add documentation for admin cli#832
TechHutTV merged 1 commit into
mainfrom
docs/admin-cli

Conversation

@jnfrati

@jnfrati jnfrati commented Jul 7, 2026

Copy link
Copy Markdown
Contributor
localhost_3000_selfhosted_maintenance_admin-cli (2)

Summary by CodeRabbit

  • Documentation
    • Added a new self-hosted Admin CLI documentation page covering maintenance commands for local user password changes, local MFA management, proxy access token lifecycle, and reverse proxy connection troubleshooting.
    • Updated identity provider docs with notes for resetting local user passwords and managing local MFA via the Admin CLI.
    • Refreshed proxy token/command examples across scaling and reverse-proxy setup pages to use consistent admin token subcommands and standardized container/config usage.
  • New Features
    • Added an “Admin CLI” link to the self-hosted Maintenance navigation.

@coderabbitai

coderabbitai Bot commented Jul 7, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: ac580218-97e8-4571-ac9d-48539b2f9226

📥 Commits

Reviewing files that changed from the base of the PR and between 0b15e84 and e21e957.

📒 Files selected for processing (6)
  • src/components/NavigationDocs.jsx
  • src/pages/selfhosted/identity-providers/enable-local-mfa.mdx
  • src/pages/selfhosted/identity-providers/local.mdx
  • src/pages/selfhosted/maintenance/admin-cli.mdx
  • src/pages/selfhosted/maintenance/scaling/multiple-proxy-instances.mdx
  • src/pages/selfhosted/migration/enable-reverse-proxy.mdx
🚧 Files skipped from review as they are similar to previous changes (5)
  • src/pages/selfhosted/maintenance/admin-cli.mdx
  • src/pages/selfhosted/identity-providers/local.mdx
  • src/components/NavigationDocs.jsx
  • src/pages/selfhosted/identity-providers/enable-local-mfa.mdx
  • src/pages/selfhosted/migration/enable-reverse-proxy.mdx

📝 Walkthrough

Walkthrough

This PR adds a self-hosted admin CLI reference, links it from Maintenance and identity-provider documentation, and updates reverse-proxy token examples to use admin token commands for combined and multi-container deployments.

Changes

Admin CLI documentation and cross-linking

Layer / File(s) Summary
Admin CLI reference and user operations
src/pages/selfhosted/maintenance/admin-cli.mdx
Adds command-prefix guidance plus instructions for changing local user passwords and resetting local MFA enrollment.
Local MFA management and notes
src/pages/selfhosted/maintenance/admin-cli.mdx, src/pages/selfhosted/identity-providers/enable-local-mfa.mdx, src/pages/selfhosted/identity-providers/local.mdx
Documents local MFA status and enable/disable commands and links related password and MFA guidance to the CLI reference.
Proxy access token and repair commands
src/pages/selfhosted/maintenance/admin-cli.mdx
Documents proxy token creation, listing, and revocation, reverse-proxy connection repair, and troubleshooting actions.
Navigation and token command updates
src/components/NavigationDocs.jsx, src/pages/selfhosted/maintenance/scaling/multiple-proxy-instances.mdx, src/pages/selfhosted/migration/enable-reverse-proxy.mdx
Adds the Maintenance sidebar link and updates combined- and multi-container proxy token examples to use admin token commands and the current config path.

Estimated code review effort: 2 (Simple) | ~15 minutes

Suggested reviewers: sunsetdrifter

Poem

A rabbit hopped in with a grin,
New CLI commands tucked right in.
admin token leads the way,
Through proxy docs refreshed today.
Hop, hop—the maintenance path is clear! 🐇

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly describes the main change: adding documentation for the admin CLI.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch docs/admin-cli

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint install timed out. The project may have too many dependencies for the sandbox.


Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@TechHutTV
TechHutTV self-requested a review July 22, 2026 13:35
@TechHutTV
TechHutTV merged commit 35d5629 into main Jul 22, 2026
3 checks passed
@TechHutTV
TechHutTV deleted the docs/admin-cli branch July 22, 2026 13:36
jnfrati added a commit to netbirdio/netbird that referenced this pull request Jul 22, 2026
## Summary

Adds a unified `admin` CLI for self-hosted instance administrators in
both the management and combined binaries.

## User Management

### `admin user change-password`
- Changes a local embedded IdP user's password.
- Selects the user with `--email` or `--user-id`.
- Reads the new password from `--password` or `--password-file`.
- Clears the user's local authentication session so the new password is
required on the next login.
- **Alias:** `admin user set-password`.

### `admin user reset-mfa`
- Resets a local embedded IdP user's MFA enrollment.
- Selects the user with `--email` or `--user-id`.
- Clears TOTP/WebAuthn enrollment data and removes the local
authentication session.
- The user will re-enroll MFA on the next login.

## MFA Management

### `admin mfa status`
- Shows whether local MFA is enabled in the account settings.
- Checks the embedded IdP client configuration and reports whether MFA
is enabled there.

### `admin mfa enable`
- Enables local MFA for embedded IdP users.
- Updates embedded IdP clients and saves the account MFA setting.
- Records an audit event on a best-effort basis.

### `admin mfa disable`
- Disables local MFA for embedded IdP users.
- Updates embedded IdP clients and saves the account MFA setting.
- Records an audit event on a best-effort basis.

## Reverse Proxy Tokens

### `admin token create --name <name> [--expires-in <duration>]`
- Creates a reverse proxy access token.
- Prints the plaintext token once, along with the token ID.
- `--expires-in` supports values such as `24h`, `30d`, or `365d`. If
omitted, the token never expires.

### `admin token list`
- Lists reverse proxy access tokens.
- Shows the token ID, name, creation date, expiration, last-used time,
and revocation status.
- **Alias:** `admin token ls`.

### `admin token revoke <token-id>`
- Revokes a reverse proxy access token.
- Revoked tokens can no longer authenticate reverse proxy instances.

## Reverse Proxy Management

### `admin proxy disconnect-all`
- Lists registered reverse proxy instances and force-marks all connected
instances as disconnected.
- Useful for repairing stale proxy state after an unclean management
server shutdown.
- Prompts for confirmation by default.
- `--dry-run` previews the changes without applying them.
- `--force` skips the confirmation prompt.
- Live proxies may appear again after their next heartbeat, reconnect,
or re-registration.

## Compatibility Commands

### `token ...`
- Deprecated top-level compatibility path.
- Behaves the same as `admin token ...`.
- Retained so existing scripts using `token create`, `token list`, or
`token revoke` continue to work.

## Changes

- Adds reusable `management/cmd/admin` command package.
- Wires `admin` into `netbird-mgmt` and `combined`.
- Adds local user password reset with existing password strength
validation.
- Adds local MFA enrollment reset by clearing Dex TOTP/WebAuthn
credentials and local auth sessions.
- Adds local MFA enable/disable/status helpers for embedded IdP
deployments.
- Moves proxy access token commands under `admin token` for a single
admin-focused CLI entry point.
- Exports `server.ValidatePassword` for reuse by CLI helpers.

## Tests

```bash
go test ./management/cmd/...
go test ./management/cmd/admin ./management/cmd ./combined/cmd
go test ./management/server -run TestValidatePassword
```

Pre-push lint also passed.


### Checklist
- [ ] Is it a bug fix
- [ ] Is a typo/documentation fix
- [x] Is a feature enhancement
- [ ] It is a refactor
- [ ] Created tests that fail without the change (if possible)
- [ ] This change does **not** modify the public API, gRPC protocols,
functionality behavior, CLI / service flags, or introduce a new feature
— **OR** I have discussed it with the NetBird team beforehand (link the
issue / Slack thread in the description). See
[CONTRIBUTING.md](https://github.com/netbirdio/netbird/blob/main/CONTRIBUTING.md#discuss-changes-with-the-netbird-team-first).

> By submitting this pull request, you confirm that you have read and
agree to the terms of the [Contributor License
Agreement](https://github.com/netbirdio/netbird/blob/main/CONTRIBUTOR_LICENSE_AGREEMENT.md).

## Documentation
Select exactly one:

- [x] I added/updated documentation for this change
- [ ] Documentation is **not needed** for this change (explain why)

### Docs PR URL (required if "docs added" is checked)
Paste the PR link from https://github.com/netbirdio/docs here:

netbirdio/docs#832

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

## Release Notes

* **New Features**
* Added self-hosted admin CLI commands for changing passwords, resetting
MFA (including WebAuthn), and managing embedded IdP client MFA
(enable/disable/status).
* Introduced a unified admin command entry point and improved
data-directory handling for embedded IdP storage.

* **Refactor**
* Centralized password strength validation into a shared exported
validator.

* **Tests**
* Added a comprehensive admin command test suite covering password
input, selectors, MFA reset, and client MFA state handling.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants